docs(pm): os-verify-lock's ordering header states headship's one measured exception — a resuming slot (#15581) - #15760

Fixes #15581

Prose correction of the ordering block in scripts/pm/os-verify-lock.sh, plus four self-test cases that pin it. No behaviour change — nothing in the acquisition path, the queue, the slot mechanism or flock is touched.

Before / after

The bullet justifying head-only flock ended, at :68 on main:

#     headship is stable — tickets sort by arrival and the ones ahead of you can
#     only disappear.

That sentence was true when written (47c1021b4, #9921, 2026-08-19) and was overtaken six days later by the slot mechanism (c312a562e, #12335, 2026-08-25), which had no reason to come back and re-read it. It now states both measured halves:

1. Headship is stable among entry-point callers with exactly one exception — a resuming slot. A parked slot keeps its ORIGINAL arrival stamp and re-enters the live queue at that stamp on resume, so a ticket ahead of you can APPEAR, not only disappear.
2. A resuming slot cannot displace an incumbent head already blocked inside flock: once a caller leaves the queue loop at position 1 it never re-reads its position, so the ordering layer has nothing left to ask it to yield with. The resumed place is delivered against callers that are merely polling, and against nobody else. The slip is exactly one position.

The header also now records, per triage's condition, that the one-position slip is accepted rather than unnoticed, with its price attached — one holder's hold, p50 95s / p90 418s / max 643s on the ledger as read for #14944, flagged as a reading of that ledger at that time and not a constant this script measures — and the known, unfixed boundary: re-checking headship after each failed flock slice does not close the window (SLICE_S is 30s, so a slot resuming inside the last slice before a release still loses), and tightening further means abandoning blocking flock for flock -n plus polling, which is a contract change to the ordering layer and the maintainer's, not a fix on sight.

Self-test: harness already existed, so the case was added

The --self-test battery already drives real multi-party scenarios (one holder plus staggered children, a SIGKILLed slot owner, a three-waiter FIFO case) against a private lock. So the card's three-party case was added rather than declined.

Isolation, quoted from the code rather than asserted. The suite exports its own lock file and every other path derives from it:

export OS_VERIFY_LOCK_FILE="$L"          # $L = mktemp -d .../os-verify-lock-selftest.XXXXXX/lock
export OS_VERIFY_LOCK_LEDGER="${L}.ledger"
LOCK_FILE="$L"; QUEUE_DIR="${L}.q"; HOLDER_FILE="${L}.holder"
LEDGER_FILE="${L}.ledger"; BOOTS_FILE="${L}.boots"; BOOTS_PROBE="${L}.boots.probe"

and in the script proper the derivations are LOCK_FILE from OS_VERIFY_LOCK_FILE (:329), QUEUE_DIR/HOLDER_FILE from LOCK_FILE (:338, :339), LEDGER_FILE (:344), BOOTS_FILE (:1069). The shared /tmp/os-heavy-verify.lock, its ledger and its boots file are never named by any test, and --status read the shared lock as state: lock is free, queue: empty both before and after this work.

Four cases, at da4bb1651:

✓ a resumed slot re-enters AHEAD of newcomers that arrived while it was parked
✓ so the resumed place is delivered against a caller that is merely polling
✓ but a resuming slot does NOT displace the incumbent head inside flock
✓ so the slip is exactly one position — three parties, one overtake

Scenario, exactly the card's: one holder; a polite caller that obeys a 2s budget, times out and parks; newcomer A (only live ticket, so it takes the head and blocks in flock); newcomer B (position 2, polling); the returner resuming the parked place with a stamp older than either newcomer. Acquisition order A R B, and the live queue read while A is inside flock has the returner's ticket sorting first.

Why the third case is not flaky. It rests on the incumbent winning the wake race between two blocked flock waiters. Measured before pinning it: 14/14 reproductions of ARB in an isolated harness (6 idle, 8 with the box loaded to a 1-minute load average of 11.7), and 15/15 first-blocker-won at the raw primitive on this kernel.

Verification

Exit codes captured before any pipe; verdict lines quoted as the gate printed them.

16 of the 24 derived gate commands ran green. The other 8 are ⊘ NOT MEASURED, each by name and each a missing dependency in this container, not a red gate:

• node packages/lint/scripts/check-reference-carrier-shape.mjs and its --self-test — exit 3, PREREQUISITE NOT MET — the dependency typescript is not installed
• node scripts/check-ci-filter-parity.mjs — exit 3, dependency yaml
• node scripts/check-closing-keyword-parity.mjs and its --self-test — exit 3, dependency yaml
• pnpm check:driver-memory-census — exit 3, dependency typescript
• node scripts/check-comment-mask-corpus.mjs — exit 1, ERR_MODULE_NOT_FOUND for @typescript-eslint/parser (a missing module, not a gate failure)
• pnpm --filter @objectstack/spec run check:llms-txt — exit 1, sh: 1: tsx: not found

CI runs all of them.

Changeset

skip-changeset. AGENTS.md: a changeset is owed for "anything that publishes … ⛔ never skip-changeset: that label is for a diff that publishes nothing from any released package." This diff is one file under scripts/pm/, which no package publishes.

🤖 Generated with Claude Code

https://claude.ai/code/session_012zGPuVVX3deAx9LdjK8jCk

Generated by Claude Code